TI 15.4-Stack Software Development Platform¶

Installing the SDK¶

To install the SimpleLink CC13x0 SDK, run the installer: simplelink_cc13x0_sdk_1_30_00_xx.exe

The default TI 15.4-Stack install path is:

C:\ti\simplelink_cc13x0_sdk_1_30_00_xx\examples\rtos\CC1350_LAUNCHXL\ti154stack

(if using a CC1350) or

C:\ti\simplelink_cc13x0_sdk_1_30_00_xx\examples\rtos\CC1310_LAUNCHXL\ti154stack

(if using a CC1310).

In addition to TI 15.4-Stack code, documentation, and projects, installing the SDK also installs the TI-RTOS bundle and the XDC tools, if not already installed. Table 1. lists the software and tools that are supported and tested with this SDK. Check the TI 15.4-Stack Wiki for the latest supported tool versions.

Code Composer Studio¶

Code Composer Studio (CCS) provides a suite of tools that are used to develop applications that run on TI’s MCUs and embedded processors. CCS contains many features that go beyond the scope of this document—more information can be found on the CCS website. Check the CC13x0 SimpleLink SDK release notes to see which CCS version to use.

The following describes installing and configuring the correct version of CCS and the necessary tools.

1. Download CCS 7.1 from the Download CCS wiki page.
2. Launch the CCS installer.
3. On the Processor Support menu (see Figure 5.), expand SimpleLink Wireless MCUs and select SimpleLink CC13xx and CC26xx Wireless MCUs

Figure 5. Processor Support Menu Selections

1. Click the Next button, then click the Finish button.
2. After CCS has installed, apply all available updates by selecting Help → Check for Updates.

Configure CCS¶

This section explains how to configure CCS for development and debugging. It also provides information on useful CCS IDE settings (see Useful CCS IDE Settings)

Using CCS¶

This section describes how to open and build an existing project. The Sensor project is used as an example. However, all of the CCS projects included in the development kit have a similar structure.

Importing SDK Projects¶

Launch the CCS IDE and prepare to import the TI 15.4-Stack projects from the installed SDK:

1. Select Project → Import CCS Projects

2. Select Select search-directory: and click the Browse… button.

3. Navigate to

   C:\ti\simplelink_cc13x0_sdk_1_30_00_xx\examples\rtos\CC1350_LAUNCHXL\ti154stack
   

   and click the OK button (see Figure 6.). If using CC1310, navigate to

   C:\ti\simplelink_cc13x0_sdk_1_30_00_xx\examples\rtos\CC1310_LAUNCHXL\ti154stack
   

Figure 6. Import SDK Projects Menu Selection

4. The Discovered projects box now lists the projects that have been found. Select the Copy projects into workspace checkbox, click the Select All button, and last click the Finish button to import a copy of each SDK project into the workspace (see Figure 7.).

   Note

   In the following sections, the project names for the CC1310 and CC1350 platforms are referred to as CC13x0. Replace x with either 1 or 5 depending on the wireless MCU being used.

Figure 7. CCS Project Import Pane

Workspace Overview¶

The workspace now contains all projects needed to build downloadable images. The following examples build a Sensor image, to produce a functional sensor device.

In the Project Explorer pane, click on the sensor_cc13x0lp project to make it active. Click on the arrow to the left of the project to expand its contents, as shown in Figure 8..

Figure 8. CCS Project Explorer Pane

In Figure 8., all folders (under the sensor_cc13x0lp project) except for sensor_cc13x0lp can be considered input folders, which contain source code files, header files, and configuration files used to compile and link the application. The sensor_cc13x0lp folder contains output files, which include programmable images and the linker map.

Compiling and Linking¶

All example projects in the SDK are ready to build out-of-the-box meaning they are preconfigured for use with a specific target board, in this case the CC13x0 LaunchPad. To build a Sensor Application image that is ready to program onto a LaunchPad board, select Project → Rebuild Project. The Console pane of the IDE displays the individual results of source file compilations, followed by the linker results, as shown in Figure 9..

Figure 9. CCS Project Console Pane

In Figure 9., the output folder sensor_cc13x0lp is populated with results from a successful build of the Sensor Application. Two programmable output files have been produced, sensor_cc13x0lp.out and sensor_cc13x0lp.hex, along with a detailed linker map file, sensor_cc13x0lp.map.

Downloading Hex Files¶

As shown in Compiling and Linking, the CCS linker produces .hex files that are ready for direct download to the target hardware. The hex image can be downloaded to a target device by a stand-alone tool, such as the SmartRF Flash Programmer 2, shown in Figure 10..

Figure 10. Programming Hex Files

As shown in Figure 10., SmartRF Flash Programmer 2 can be used to program the prebuilt hex file using the Flash image(s) → Single feature. Use the Browse… button to select the following files:

\examples\rtos\CC1350_LAUNCHXL\ti154stack\hexfiles\default\sensor_default.hex

After connecting a CC13x0 LaunchPad target board to one of the USB ports of the PC, the XDS110 instance becomes listed in the Connected devices panel. Select the listed device by clicking on the CC1310 icon. Programming the CC13x0 LaunchPad is accomplished through the following sequence (see Figure 10.).

1. Select the Erase action, using the Pages in image option.
2. Select the Program action, using the Entire source file option.
3. Select the Verify action, using the Readback option.
4. Press the Play button (blue icon at the lower right corner of the Actions panel).
5. Observe the device programming feedback in the Status panel. It shows Success! when finished.
6. Exit the SmartRF Flash Programmer 2 and power cycle the LaunchPad to run the application.

Debugging¶

When debugging is necessary, .out files produced by the linker are downloaded and run from the CCS IDE. The following procedure would typically be used to debug the program.

Continuing with the Sensor example project, the compiled program can be downloaded to the target and a debug session initiated by selecting: Run → Debug on the IDE, as shown in Figure 11..

Figure 11. Debugging Sensor Application

In Figure 11., the IDE has switched from the CCS Edit perspective to CCS Debug and shows the program counter stopped at main(). From this starting point, the developer can single-step through source code, set and run-to breakpoints, and run the program using icons at the top of the display. During a debug session, the user can switch between the CCS Edit and CCS Debug perspectives, as necessary, to view project files and perform debugging operations.

Useful CCS IDE Settings¶

The CCS provides a large number of configurable settings that can be used to customize the IDE and individual projects. The following examples do not alter the generated program code, but they can improve the developer’s experience when working with CCS projects. The CCS can reduce project compilation time by taking advantage of multiple processor cores on the development computer.

To use this feature, navigate to Project → Properties → Build → Behavior and select Enable parallel build, as shown in Figure 12..

Figure 12. Properties for sensor_cc13x0lp

CCS users can control the amount of information that is displayed in the Console portion of the screen during project compilation and linking, ranging from Verbose to Super quiet. To change this setting, navigate to Window → Preferences → Code Composer Studio → Build and select an entry from the Console verbosity level drop-down, as shown in Figure 13.

Figure 13. Console Verbosity Level Preferences

Using Nonvolatile Memory¶

Thetion NV area of flash is used for storing persistent data for the application. TI 15,4-Stack provides two implementations of NV. One uses one page of internal flash, while the other uses two. By default example applications use one page NV. For more information on one page NV please refer to nvocop.c which describes the implementation details. Also nvoctp.c describes the implementation details of the two page NV. The last page in flash is the CCA page, depending on whether one page or two page NV is used one or two pages before the last page (CCA) are defined as the NV area. The example projects use the NV driver with the API defined in nvintf.h.

The NV driver is set up in main.c:

#ifdef NV_RESTORE
    /* Setup the NV driver */
    NVOCTP_loadApiPtrs(&Main_user1Cfg.nvFps);

    if(Main_user1Cfg.nvFps.initNV)
    {
        Main_user1Cfg.nvFps.initNV( NULL);
    }
#endif

Then the applications use the function pointers in Main_user1Cfg to call the NV functions defined in nvintf.h:

//! Structure of NV API function pointers
typedef struct nvintf_nvfuncts_t
{
    //! Initialization function
    NVINTF_initNV initNV;
    //! Compact NV function
    NVINTF_compactNV compactNV;
    //! Create item function
    NVINTF_createItem createItem;
    //! Delete NV item function
    NVINTF_deleteItem deleteItem;
    //! Read item function
    NVINTF_readItem readItem;
    //! Write item function
    NVINTF_writeItem writeItem;
    //! Write existing item function
    NVINTF_writeItemEx writeItemEx;
    //! Get item length function
    NVINTF_getItemLen getItemLen;
} NVINTF_nvFuncts_t;

The following is an example of a write from csf.c:

static void updateDeviceListItem(Llc_deviceListItem_t *pItem)
{
    if((pNV != NULL) && (pItem != NULL))
    {
        int idx;
        idx = findDeviceListIndex(&pItem->devInfo.extAddress);
        if(idx != DEVICE_INDEX_NOT_FOUND)
        {
            NVINTF_itemID_t id;

            /* Setup NV ID for the device list record */
            id.systemID = NVINTF_SYSID_APP;
            id.itemID = CSF_NV_DEVICELIST_ID;
            id.subID = (uint16_t)idx;

            /* write the device list record */
            pNV->writeItem(id, sizeof(Llc_deviceListItem_t), pItem);
        }
    }
}

The following is an example of a read from csf.c:

bool Csf_getNetworkInformation(Llc_netInfo_t *pInfo)
{
    if((pNV != NULL) && (pNV->readItem != NULL) && (pInfo != NULL))
    {
        NVINTF_itemID_t id;

        /* Setup NV ID */
        id.systemID = NVINTF_SYSID_APP;
        id.itemID = CSF_NV_NETWORK_INFO_ID;
        id.subID = 0;
        /* Read Network Information from NV */
        if(pNV->readItem(id, 0, sizeof(Llc_netInfo_t), pInfo) == NVINTF_SUCCESS)
        {
            return(true);
        }
    }
    return(false);
}

The NV system is a collection of NV items. Each item is unique and have the following pieces to it (defined in nvintf.h).:

/**
*  NV Item Identification structure
*/

typedef struct nvintf_itemid_t
{
    //! NV System ID - identifies system (ZStack, BLE, App, OAD...)
    uint8_t systemID;
    //! NV Item ID
    uint16_t itemID;
    //! NV Item sub ID
    uint16_t subID;
} NVINTF_itemID_t;

System Stack¶

Besides the RTOS and ICall heaps previously mentioned, there are other sections of memory to consider. As described in TI-RTOS Overview, each task has its own runtime stack for context switching. Furthermore, another runtime stack is used by the RTOS for main(), HWIs, and SWIs. This system stack is allocated in the Application linker file, to be placed at the end of the RAM of the Application.

For CCS, the RTOS system stack is defined by the Program.stack parameter in the app.cfg RTOS configuration file.

/* main() and Hwi, Swi stack size */
Program.stack = 1280;

Then the RTOS system stack is placed by the linker in the RAM space of the Application::

/* Create global constant that points to top of stack */
/* CCS: Change stack size under Project Properties */
STACK_TOP = stack + STACK_SIZE;

Dynamic Memory Allocation¶

The system uses two heaps for dynamic memory allocation. It is important to understand the use of each heap so that the application designer maximizes the use of available memory. The RTOS is configured with a small heap in the app.cfg RTOS configuration file.

var HeapMem = xdc.useModule('xdc.runtime.HeapMem');
BIOS.heapSize = 1724;

This heap (HeapMem) is used to initialize RTOS objects as well as allocate the TI 15.4-Stack task runtime stack. This size of this heap has been chosen to meet the system initialization requirements. Due to the small size of this heap, TI does not recommend allocating memory from the RTOS heap for general application use. For more information on the TI-RTOS heap configuration, refer to the Heap Implementations section of the TI-RTOS SYS/BIOS Kernel User’s Guide.

Instead, a separate heap must be used by the Application. The ICall module statically initializes an area of Application RAM, heapmgrHeapStore, which can be used by the various tasks. The size of this ICall heap is defined by the preprocessor definition of the Application HEAPMGR_SIZE, and is set to 0 by default for the Collector and Sensor projects; a value of 0 means that all unused RAM is given to the ICall heap. Although the ICall heap is defined in the Application project, it is also shared with the TI 15.4-Stack APIs which allocate memory from the ICall heap. To manually change the size of the ICall heap, adjust the value of the preprocessor symbol HEAPMGR_SIZE in the Application project to a value other than 0.

To profile the amount of ICall heap used, define the HEAPMGR_METRICS preprocessor symbol in the Application project. Refer to heapmgr.h in Components\applib\heap for available heap metrics. The following is an example of dynamically allocating a variable length (n) array using the ICall heap.:

//define pointer
uint8_t *pArray;

// Create dynamic pointer to array.
if (pArray = (uint8_t*)ICall_malloc(n*sizeof(uint8_t)))
{
    //fill up array
}
else
{
    //not able to allocate
}

The following is an example of freeing the previous array.:

ICall_free(pMsg->payload);

A Note on Initializing RTOS Objects¶

Due to the limited size of the RTOS heap, TI strongly recommends that users construct and not create RTOS objects. To illustrate this recommendation, consider the difference between the Clock_construct() and Clock_create() functions. Listing 1. shows the definitions of these functions from the SYS/BIOS API.

// Allocate and initialize a new instance object and return its handle
Clock_Handle Clock_create(Clock_FuncPtr, UInt timeout,  \
    const Clock_params *params, Error_Block *eb);

// Initialize a new instance object inside the provided structure
Void Clock_construct(Clock_Struct *structP, Clock_FuncPtr clockFxn, \
    UInt timeout, const Clock_Params *params);

By declaring a static Clock_Struct object and passing this object to Clock_construct(), the .DATA section for the actual Clock_Struct is used, not the limited RTOS heap. Conversely, Clock_create() causes the RTOS to allocate Clock_Struct using the limited heap of the RTOS. As much as possible, this method is how clocks and RTOS objects in general, should be initialized throughout the project. If creating RTOS objects must be used, the size of the RTOS heap may need to be adjusted in app.cfg.